{
 "metadata": {},
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Mayabi: mlab\n",
      "======================================================================\n",
      "\n",
      "||\\<\\#80FF80\\> This page is about the tvtk.tools.mlab module. You are\n",
      "strongly advised to use the more recent [mayavi.mlab\n",
      "module](http://enthought.github.com/mayavi/mayavi/mlab.html) which can\n",
      "also be used from *ipython -wthread* or as a library inside another\n",
      "application.||\n",
      "\n",
      "The \\`\\`mlab.py\\`\\` module allows for simple 3D plotting of objects. It\n",
      "provides an object oriented approch to 3d visualization.\n",
      "\n",
      "It relies on the simple TVTK module, rather than on the full blown\n",
      "Mayavi application. As a result it has less dependencies. However, it is\n",
      "harder to extend and more limited. The developers are not planning any\n",
      "feature addition to this module, and we strongly advise you to use the\n",
      "Mayavi mlab module, which provides the same usecases, but with more\n",
      "functionalities and is under constant development. For more information,\n",
      "you can read [the relevant section of the Mayavi user\n",
      "guide](http://enthought.github.com/mayavi/mayavi/mlab.html)\n",
      "\n",
      "''' Table of Contents '''\n",
      "\n",
      "<TableOfContents>\n",
      "\n",
      "A Simple Example\n",
      "----------------\n",
      "\n",
      "||\\<\\#FF8080\\> **Important:** All these examples must be run in \"ipython\n",
      "-wthread\" or in a Wx application (like pycrust, or the Mayavi2\n",
      "application). They **will not work** if you don't use this option.||\n",
      "\n",
      "Start with \\`ipython -wthread\\` and paste the following code::"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import scipy\n",
      "\n",
      "# prepare some interesting function:\n",
      "def f(x, y):\n",
      "    return 3.0*scipy.sin(x*y+1e-4)/(x*y+1e-4)\n",
      "\n",
      "x = scipy.arange(-7., 7.05, 0.1)\n",
      "y = scipy.arange(-5., 5.05, 0.1)\n",
      "\n",
      "# 3D visualization of f:\n",
      "from enthought.tvtk.tools import mlab\n",
      "fig = mlab.figure()\n",
      "s = mlab.SurfRegular(x, y, f)\n",
      "fig.add(s)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_mlab/simple_example.png)\n",
      "\n",
      "Changing axis and colour\n",
      "------------------------"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from scipy import *\n",
      "\n",
      "[x,y]=mgrid[-5:5:0.1,-5:5:0.1]\n",
      "r=sqrt(x**2+y**2)\n",
      "z=sin(3*r)/(r)\n",
      "\n",
      "from enthought.tvtk.tools import mlab\n",
      "\n",
      "# Open a viewer without the object browser:\n",
      "f=mlab.figure(browser=False)\n",
      "\n",
      "s=mlab.Surf(x,y,z,z)\n",
      "f.add(s)\n",
      "s.scalar_bar.title='sinc(r)'\n",
      "s.show_scalar_bar=True\n",
      "# LUT means \"Look-Up Table\", it give the mapping between scalar value and color\n",
      "s.lut_type='blue-red'\n",
      "# The current figure has two objects, the outline object originaly present, \n",
      "# and the surf object that we added.\n",
      "f.objects[0].axis.z_label='value'\n",
      "t=mlab.Title()\n",
      "t.text='Sampling function'\n",
      "f.add(t)\n",
      "# Edit the title properties with the GUI:\n",
      "t.edit_traits()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_mlab/tvtk.mlab_example.png)\n",
      "\n",
      "List of different functionalities\n",
      "---------------------------------\n",
      "\n",
      "The implementation provided here is object oriented and each\n",
      "visualization capability is implemented as a class that has traits. So\n",
      "each of these may be configured. Each visualization class derives\n",
      "(ultimately) from MLabBase which is responsible for adding/removing its\n",
      "actors into the render window. The classes all require that the\n",
      "RenderWindow be a \\`pyface.tvtk.scene.Scene\\` instance (this constraint\n",
      "can be relaxed if necessary later on).\n",
      "\n",
      "This module offers the following broad class of functionality:\n",
      "\n",
      "`*\u00a0`**`Figure`**\\\n",
      "`\u00a0This\u00a0basically\u00a0manages\u00a0all\u00a0of\u00a0the\u00a0objects\u00a0rendered.\u00a0\u00a0Just\u00a0like`\\\n",
      "`\u00a0figure\u00a0in\u00a0any\u00a0Matlab\u00a0like\u00a0environment.\u00a0\u00a0A\u00a0convenience\u00a0function`\\\n",
      "`` \u00a0called\u00a0`figure`\u00a0may\u00a0be\u00a0used\u00a0to\u00a0create\u00a0a\u00a0nice\u00a0Figure\u00a0instance. ``\n",
      "\n",
      "`*\u00a0`**`Glyphs`**\\\n",
      "`\u00a0This\u00a0and\u00a0its\u00a0subclasses\u00a0let\u00a0one\u00a0place\u00a0glyphs\u00a0at\u00a0points\u00a0specified`\\\n",
      "`` \u00a0as\u00a0inputs.\u00a0\u00a0The\u00a0subclasses\u00a0are:\u00a0`Arrows`,\u00a0`Cones`,\u00a0`Cubes`,\u00a0 ``\\\n",
      "`` \u00a0`Cylinders`,\u00a0`Spheres`,\u00a0and\u00a0`Points`. ``\n",
      "\n",
      "`*\u00a0`**`Line3`**\\\n",
      "`\u00a0Draws\u00a0lines\u00a0between\u00a0the\u00a0points\u00a0specified\u00a0at\u00a0initialization\u00a0time.`\n",
      "\n",
      "`*\u00a0`**`Outline`**\\\n",
      "`\u00a0Draws\u00a0an\u00a0outline\u00a0for\u00a0the\u00a0contained\u00a0objects.`\n",
      "\n",
      "`*\u00a0`**`Title`**\\\n",
      "`\u00a0Draws\u00a0a\u00a0title\u00a0for\u00a0the\u00a0entire\u00a0figure.`\n",
      "\n",
      "`*\u00a0`**`LUTBase`**\\\n",
      "`\u00a0Manages\u00a0a\u00a0lookup\u00a0table\u00a0and\u00a0a\u00a0scalar\u00a0bar\u00a0(legend)\u00a0for\u00a0it.\u00a0\u00a0This\u00a0`\\\n",
      "`\u00a0is\u00a0subclassed\u00a0by\u00a0all\u00a0classes\u00a0that\u00a0need\u00a0a\u00a0LUT.`\n",
      "\n",
      "`*\u00a0`**`SurfRegular`**\\\n",
      "`\u00a0MayaVi1's\u00a0imv.surf\u00a0like\u00a0functionality\u00a0that\u00a0plots\u00a0surfaces\u00a0given\u00a0x\u00a0(1D),\u00a0y(1D)`\\\n",
      "`\u00a0and\u00a0z\u00a0(or\u00a0a\u00a0callable)\u00a0arrays.`\n",
      "\n",
      "`*\u00a0`**`SurfRegularC`**\\\n",
      "`\u00a0Also\u00a0plots\u00a0contour\u00a0lines.`\n",
      "\n",
      "`*\u00a0`**`TriMesh`**\\\n",
      "`\u00a0Given\u00a0triangle\u00a0connectivity\u00a0and\u00a0points,\u00a0plots\u00a0a\u00a0mesh\u00a0of\u00a0them.`\n",
      "\n",
      "`*\u00a0`**`FancyTriMesh`**\\\n",
      "`\u00a0Plots\u00a0the\u00a0mesh\u00a0using\u00a0tubes\u00a0and\u00a0spheres\u00a0so\u00a0its\u00a0fancier.`\n",
      "\n",
      "`*\u00a0`**`Mesh`**\\\n",
      "`\u00a0Given\u00a0x,\u00a0y\u00a0generated\u00a0from\u00a0scipy.mgrid,\u00a0and\u00a0a\u00a0z\u00a0to\u00a0go\u00a0with\u00a0it.\u00a0\u00a0Along\u00a0with\u00a0optional`\\\n",
      "`\u00a0scalars.\u00a0\u00a0This\u00a0class\u00a0builds\u00a0the\u00a0triangle\u00a0connectivity\u00a0(assuming\u00a0that\u00a0x,\u00a0y\u00a0are\u00a0from`\\\n",
      "`\u00a0scipy.mgrid)\u00a0and\u00a0builds\u00a0a\u00a0mesh\u00a0and\u00a0shows\u00a0it.`\n",
      "\n",
      "`*\u00a0`**`FancyMesh`**\\\n",
      "`\u00a0Like\u00a0mesh\u00a0but\u00a0shows\u00a0the\u00a0mesh\u00a0using\u00a0tubes\u00a0and\u00a0spheres.`\n",
      "\n",
      "`*\u00a0`**`Surf`**\\\n",
      "`\u00a0This\u00a0generates\u00a0a\u00a0surface\u00a0mesh\u00a0just\u00a0like\u00a0Mesh\u00a0but\u00a0renders\u00a0the\u00a0mesh\u00a0as`\\\n",
      "`\u00a0a\u00a0surface.`\n",
      "\n",
      "`*\u00a0`**`Contour3`**\\\n",
      "`\u00a0Shows\u00a0contour\u00a0for\u00a0a\u00a0mesh.`\n",
      "\n",
      "`*\u00a0`**`ImShow`**\\\n",
      "`\u00a0Allows\u00a0one\u00a0to\u00a0view\u00a0large\u00a0numeric\u00a0arrays\u00a0as\u00a0image\u00a0data\u00a0using\u00a0an\u00a0image`\\\n",
      "`` \u00a0actor.\u00a0\u00a0This\u00a0is\u00a0just\u00a0like\u00a0MayaVi1's\u00a0`mayavi.tools.imv.viewi`. ``\n",
      "\n",
      "To see nice examples of all of these look at the \\`test\\_\\*\\` functions\n",
      "at the end of this file. Here is a quick example that uses these test\n",
      "functions:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.tvtk.tools import mlab\n",
      "f = mlab.figure()\n",
      "mlab.test_surf(f) # Create a spherical harmonic.\n",
      "f.pop() # Remove it.\n",
      "mlab.test_molecule(f) # Show a caffeine molecule.\n",
      "f.renwin.reset_zoom() # Scale the view.\n",
      "f.pop() # Remove this.\n",
      "mlab.test_lines(f) # Show pretty lines.\n",
      "f.clear() # Remove all the stuff on screen."
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    }
   ],
   "metadata": {}
  }
 ]
}